package com.mmg.cosplay.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.mmg.cosplay.entity.po.KnowledgeDocument;
import dev.langchain4j.data.segment.TextSegment;
import org.springframework.web.multipart.MultipartFile;

import java.util.List;

/**
 * 知识库服务接口
 * 
 * @author fly
 * @since 2025-9-24
 */
public interface IKnowledgeService extends IService<KnowledgeDocument> {

    /**
     * 为指定角色添加文本知识
     * 
     * @param roleId 角色ID
     * @param title 文档标题
     * @param content 文档内容
     * @return 知识文档ID
     */
    Long addTextKnowledge(Long roleId, String title, String content);

    /**
     * 为指定角色上传文件知识
     * 
     * @param roleId 角色ID
     * @param file 上传的文件
     * @return 知识文档ID
     */
    Long addFileKnowledge(Long roleId, MultipartFile file);

    /**
     * 删除知识文档
     * 
     * @param documentId 文档ID
     * @param roleId 角色ID（用于验证权限）
     */
    void deleteKnowledge(Long documentId, Long roleId);

    /**
     * 获取角色的所有知识文档
     * 
     * @param roleId 角色ID
     * @return 知识文档列表
     */
    List<KnowledgeDocument> getKnowledgeByRole(Long roleId);

    /**
     * 在指定角色的知识库中搜索相关内容
     * 
     * @param roleId 角色ID
     * @param query 查询文本
     * @param maxResults 最大返回结果数
     * @return 相关文本片段列表
     */
    List<TextSegment> searchKnowledge(Long roleId, String query, int maxResults);

    /**
     * 清空指定角色的知识库
     * 
     * @param roleId 角色ID
     */
    void clearRoleKnowledge(Long roleId);
}